home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / compress / convr310.zip / CONVERT.DOC < prev    next >
Text File  |  1993-09-25  |  11KB  |  259 lines
  1. CONVERT.DOC
  2. 09/25/93
  3.  
  4. Program written by:
  5.                         Bruce Guthrie
  6.                         Room H-4885
  7.                         U.S. Dept of Commerce/ESA/OBA/BSISD
  8.                         Washington, D.C. 20230
  9.  
  10.                         (202) 482-3234
  11.  
  12. You may freely copy and re-distribute this program; however, the U.S.
  13. Department of Commerce neither guarantees nor assures compatibility of the
  14. program with all computer software or hardware.
  15.  
  16. Foreign users:  Please provide an Internet address in all correspondence or
  17. and just e-mail your problems to me at bgu@cu.nih.gov
  18.  
  19.  
  20. Introduction:
  21.  
  22. This program converts data files from one format to another.  Specifically, it
  23. can take the following input file types:
  24.  
  25.         ASCII-delimited file
  26.         Fixed-field file
  27.         dBaseIII (.DBF) file
  28.  
  29. and create the following files:
  30.  
  31.         ASCII-delimited file
  32.         Fixed-field file
  33.         Lotus 1-2-3 worksheet (.WKS)
  34.         dBaseIII (.DBF) file
  35.  
  36. An ASCII-delimited file is one which typically has double quotes around each
  37. character field (the quotes are optional in CONVERT) and typically commas
  38. between fields.  Leading and trailing spaces are removed from character as well
  39. as all other values.
  40.  
  41. A fixed-field file places each field in the same column positions on each
  42. record.  The lengths of the fields are the same from record to record.
  43.  
  44. As an example, these might be an ASCII-delimited records:
  45.  
  46.         "Economic Bulletin Board","202 482-3870",35
  47.         "EBB High-Speed","202 482-2584",100
  48.  
  49. Fixed-field file records might look like this for the same data:
  50.  
  51.         Economic Bulletin Board 202 482-3870  35
  52.         EBB High-Speed          202 482-2584 100
  53.  
  54. WKS files are supported directly by Lotus 1-2-3 (all versions) as well as most
  55. other spreadsheet programs.  DBF files are supported by dBaseIII, dBaseIII+,
  56. dBaseIV, and most other data base management programs.
  57.  
  58.  
  59.  
  60. Field definition file:
  61.  
  62. Unless you are reading a dBase file, the CONVERT program requires a field
  63. definition file to figure out the characteristics for each field and also to set
  64. certain file characteristics.  The definition file can be created with any text
  65. editor.  The definition file consists of several records with the following
  66. fields separated by spaces.  Except for the record type indicator (which must
  67. begin in column 1), all other fields can be placed in any columns:
  68.  
  69.         (1) record type (see below)
  70.         (2) length of field on input
  71.         (3) number of decimal places for numeric data (if you don't know,
  72.             put a "?" here; for non-numeric data, a "0" is fine) on output
  73.         (4) length of field on output
  74.  
  75. Any characters after the field length are treated as comment fields.  You would
  76. typically use this to enter the field name or column position or any other
  77. information of use to you.
  78.  
  79. The data record types accepted by CONVERT are as follows:
  80.  
  81.         type C = character data
  82.              N = numeric
  83.              L = logical (T or F)
  84.              D = date (in yyyymmdd format)
  85.  
  86. Other records accepted in the field definition file are as follows:
  87.  
  88.         type ; = comment (anything after semi-colon is ignored)
  89.              X = lines to ignore; specify "X=string" and any records
  90.                  which begin with the "string" characters will be ignored;
  91.                  defaults to X="_
  92.              Z = delimiter between fields; defaults to Z=,
  93.  
  94. The data fields (types C, N, L, and D) should be in the order the fields are
  95. found in the source file.
  96.  
  97. You can only have one instance each of X or Z records.
  98.  
  99.  
  100. Note that for fixed field files, you have to account for every byte in the file.
  101. If you have something like this:
  102.  
  103.         12345678_1_2345678_2_2345678_3      (column positions)
  104.         APPLE    X Y    12 BANANAS
  105.  
  106. Even though you may think you only have five fields, the following .DEF file
  107. will NOT work:
  108.  
  109.         ; Bad .DEF file:  Note does not account for blank spaces
  110.         C   8 0   8 Fruit1
  111.         C   1 0   1 Class1
  112.         C   1 0   1 Class2
  113.         N   5 0   5 Value
  114.         C  11 0  11 Fruit2
  115.  
  116. You may want the Fruit1 field to be in columns 1 through 8 and Class1 to be in
  117. column 10 but CONVERT will not know to skip column 9 so it will start reading
  118. Class1 beginning in column 9, Class2 beginning in column 10, etc.  To drop the
  119. blank positions, you have to add dummy fields on input and ask for them to be
  120. dropped on output:
  121.  
  122.         ; Good .DEF file:  Spaces between fields are accounted for
  123.         C   8 0   8 Fruit1
  124.         C   1 0   0 Filler
  125.         C   1 0   1 Class1
  126.         C   1 0   0 Filler
  127.         C   1 0   1 Class2
  128.         C   1 0   0 Filler
  129.         N   5 0   5 Value
  130.         C   1 0   0 Filler
  131.         C  11 0  11 Fruit2
  132.  
  133. You can also use the input field length and output field lengths to either drop
  134. fields using other formats (by specifying a zero length for the output field
  135. length) or for creating fields on output (by specifying a zero length for the
  136. input field length).  You can also use this to expand on contract a field.  For
  137. example, if Fruit1 is 8 characters long but you only want it to occupy 4
  138. characters on output (thus the field would be truncated), specify 8 for the
  139. input field length and 4 for the output field length.
  140.  
  141.  
  142.  
  143. Running the program:
  144.  
  145. Some of the default values for this routine can be set using the CONFIGWS.EXE
  146. program.
  147.  
  148. To run the program, you must specify at least one parameter (the name of the
  149. input file).  There are also some optional parameters which can be left off if
  150. you want:
  151.  
  152.     CONVERT infile [ outfile [ deffile ] ]
  153.       [ /OVERWRITE | /-OVERWRITE | /APPEND | /OVERASK ]
  154.       [ /DEF=deffile ] [ /FROM { FIXED | ASCII | ASCII=char | DBF } ]
  155.       [ /FIXED | /ASCII | /ASCII=char | /DBF ] [ /USEDEF | /NODEF ]
  156.       [ /TO { FIXED | ASCII | ASCII=char | WKS | DBF } ] [ /HEADER | /-HEADER ]
  157.       [ /SKIP | /MISSING | /ABORT ] [ /SAS ] [ /BEEP | /-BEEP ] [ /Q ] [ /? ]
  158.  
  159. "infile" is the file specification for the ASCII-delimited or fixed-field file
  160. you want converted.  You can specify a drive and path specification if
  161. necessary.  This parameter is required.
  162.  
  163. "outfile" is the file specification of the file you want to create.  You can
  164. specify a drive and path specification if necessary.  If no outfile is provided,
  165. the routine will presume you want the output file called the same thing as the
  166. infile but you want the extension to be ".FIX" (if the output file is a
  167. fixed-field file), ".PRN" (if the output file is ASCII-delimited), or ".WKS" (if
  168. the output file is to be in a WKS format).
  169.  
  170. "deffile" is the file specification for the field definition file.  You can
  171. specify a drive and path specification if necessary.  If no deffile is provided,
  172. the routine will presume it is called the same thing as the infile but it has
  173. the extension of ".DEF".  Note that the deffile can only be provided if you also
  174. specify the outfile name.
  175.  
  176. "/OVERWRITE" says to overwrite the output file if it exists already.
  177.  
  178. "/-OVERWRITE" says to abort if the output file exists already.
  179.  
  180. "/APPEND" says to append (add) to the output file if it exists already.  This
  181. option is only available if you're creating either a fixed-field or ASCII-
  182. delimited output file.
  183.  
  184. "/OVERASK" says to ask if the output file exists already.  This is typically
  185. the default but it's CONFIGWS-able.
  186.  
  187. "/FROM FIXED", "/FROM ASCII", "/FROM ASCII=char", and "/FROM DBF" specifies the
  188. format for the input file.  The routine will typically read the file and guess
  189. its format for you.  The "/FROM ASCII=char" form allows you to specify the
  190. ASCII-delimiting character (usually a comma) instead of specifying it in the
  191. definition file.
  192.  
  193. "/FIXED", "/ASCII", "/ASCII=char", and "/DBF" specifies the format for the input
  194. file.  This is a short for of the "/FROM format" specification.
  195.  
  196.  
  197. "/USEDEF" is specified for dBase input files if you want CONVERT to read an
  198. existing field-definition file.  Since dBase files contain all of the field
  199. information in the data base itself, CONVERT will normally pick up all field
  200. information from there and simply ignore any field-definition file.
  201.  
  202. "/NODEF" is specified for ASCII-delimited input files if you want CONVERT to
  203. figure out the field-definition file for you.  There are some risks in this and
  204. the operation takes longer than you may desire.  Note that CONVERT will
  205. automatically write out the field-definition file for you if you select this
  206. option.
  207.  
  208. "/TO FIXED", "/TO ASCII", "/TO ASCII=char", "/TO WKS", and "/TO DBF" tells the
  209. routine what sort of output file you'd like to create.  Typically defaults to
  210. "/TO WKS" although you can change this using the CONFIGWS.EXE program.
  211.  
  212. "/HEADER" is used in conjunction with WKS output files.  If /HEADER is in
  213. effect, the first row of the spreadsheet will contain the variable name for the
  214. cell as provided in your control file.  If none are provided, the field names
  215. will be FIELD_01 onward.  /-HEADER turns this off and is the default.  Note that
  216. the header line (if any) will show up in the output counts.
  217.  
  218. "/SKIP" says to skip records with bad data values; otherwise the routine
  219. aborts when it runs into any.  /SKIP, /MISSING, and /ABORT are mutually
  220. exclusive.
  221.  
  222. "/MISSING" says to presume any missing fields in an ASCII-delimited record
  223. should be filled in with blanks (for character fields) and 0 for numeric fields.
  224. Incomplete records are written out (unlike in /SKIP).  /SKIP, /MISSING, and
  225. /ABORT are mutually exclusive.  Note that the program will only print out the
  226. first "bad" record.  There may be others that show up after this one.
  227.  
  228. "/ABORT" says to abort when you run into bad records.  This is typically the
  229. default although you can change this using the CONFIGWS.EXE program.  /SKIP,
  230. /MISSING, and /ABORT are mutually exclusive.
  231.  
  232. "/SAS" tells the program to accept single decimal points as valid numeric data
  233. and to convert them to zeroes.  The decimal point convention is used in the SAS
  234. language to designate missing data.
  235.  
  236. "/BEEP" beeps when the program is finished.
  237.  
  238. "/-BEEP" reverses /BEEP and is typically the default.  You can change the
  239. default with the CONFIGWS.EXE program.
  240.  
  241. "/Q" turns off the line-by-line status report.
  242.  
  243. "/?" (or "/HELP" or "HELP" ) gives you the syntax for the command.
  244.  
  245.  
  246.  
  247. Restrictions and Caveats:
  248.  
  249. The program cannot handle dBase files with Memo fields.
  250.  
  251. Most spreadsheet programs restrict a given field length to being 240 characters
  252. or less.
  253.  
  254. Date fields which are in the form "yy-mm-dd" (instead of "yyyymmdd") should be
  255. declared as character fields instead of date fields.
  256.  
  257. Date fields converted for WKS files are changed into strings of the "yy-mm-dd"
  258. format.
  259.